在 kintone 應用程式當中，「Lookup」是一個非常便利的欄位類型，可以和其他應用程式做連結，透過選定的欄位值將資料從來源應用程式帶入至當前應用程式中。

應用場景如：

• 在「訂單管理」當中，使用 Lookup 選取「客戶資料」中的手機號碼，來帶入客戶的基本資訊如姓名、地址、E-mail⋯⋯等。
• 在「費用申請」當中，使用 Lookup 選取「事前申請」中的申請編號，來帶入事前申請的經費資訊。

Lookup 的觸發方式

1. 手動執行
   在記錄新增/編輯畫面中，於 Lookup 欄位輸入值後，點擊「選取」或按下「Enter」鍵
2. 程式觸發
   透過客製化程式碼（包含外掛），對 event object 賦值： event.record.Lookup欄位.lookup = true 觸發查找。
3. CSV/Excel 匯入記錄
4. REST API 更新記錄

手動執行 Lookup 的行為

手動執行 Lookup 時，系統會先對輸入值進行「搜尋」：

• 若結果只有一筆，會自動帶入資料。
• 若結果有兩筆（含）以上，會跳出選擇視窗，使用者需自行挑選。

💡Lookup 的搜尋方式與 kintone 的一般搜尋邏輯一致，詳情可參考 官方線上說明。

範例一：手機號碼（不加分隔符）

來源編號：

• 0988111111
• 0988222222

「0988111111」與「0988222222」會分別被視為完整單詞，必須輸入「0988111111」或「0988222222」才能成功查到，輸入「0988」不會有結果。

範例二：手機號碼（加分隔符）

來源編號：

• 0977-000-000
• 0988-111-111
• 0988-111-222
• 0988-222-222

由於符號會將字串拆成單詞，輸入「0988」時會帶出三筆候選資料；輸入「0977」則只有唯一符合，會自動帶入。

使用 lookup = true 的行為

event.record.Lookup欄位.lookup = true

透過程式碼將 Lookup 欄位的 lookup 屬性值設為 true 時：

• 若搜尋結果只有一筆，會自動帶入。
• 若結果有兩筆以上，則不會完成 Lookup，也不會跳出視窗。

這與手動操作的差異需要特別注意。

匯入與 API 更新時的行為

• 使用 CSV/Excel 匯入 或 REST API 更新記錄 時，並不會進行模糊搜尋，而是直接比對值，需要完全相符才可帶入資料。
• 與手動或程式觸發不同，由於不會進行搜尋，只要來源值為唯一值，即可正確帶入資料。

資料設計時的注意事項

理解以上規則後，建議在設計應用程式時考量以下幾點：

1. 來源值是否唯一

不論是否使用匯入或 API 更新，都建議將來源值設為唯一值，避免 Lookup 時無法判定要帶入哪一筆。

2. 是否需要模糊搜尋

若希望輸入部分文字後能帶出多筆資料供選擇，設計編碼時應加入分隔符，例如：AAA-01、AAA-02、AAA-03，而非 AAA01、AAA02、AAA03。

3. 是否使用程式自動 Lookup

當來源值可能是其他值的部分單詞時，要特別小心。
例如編碼有 AAA、AAA-01、AAA-02 ：

• 手動輸入 AAA → 會跳出以上三個選項。
• lookup = true → 因為搜尋結果包含多筆，導致無法自動帶入。

這是許多使用者在資料設計時常見的陷阱。

結語

Lookup 欄位雖然方便，但其行為在不同情境下有一些差異。若在資料設計時沒有考慮到唯一值、單詞拆分、或程式自動觸發的限制，往往會造成 Lookup 無法正常帶入的問題。建議在規劃應用程式時，就先釐清資料的編碼規則與使用場景，確保 Lookup 能穩定發揮作用，避免後續在匯入或 API 操作時遇到意料之外的錯誤。